---
sidebar_label: From Action
sidebar_position: 3
description: Adding action relationships with Postgres tables in Hasura
keywords:
  - hasura
  - docs
  - action relationship
  - remote join
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import Thumbnail from '@site/src/components/Thumbnail';
import GraphiQLIDE from '@site/src/components/GraphiQLIDE';

# Postgres: Action to Database Relationships

## Introduction

Action relationships allow you to join data across tables and actions. Once you create relationships between types from
your database and types created from actions, you can then "join" them by running GraphQL queries.

[Actions](/actions/overview.mdx) are a way to extend Hasura’s schema with custom business logic using custom queries and
mutations. The resolvers for these custom fields are written in REST endpoints. They are especially useful for setting
up serverless functions as resolvers.

## Create an action relationship

### Step 1: Create an action

Create an action either [from scratch](/actions/create.mdx) or [derived from an existing mutation](/actions/derive.mdx).

### Step 2: Define and create the relationship

The following values can be defined for an action relationship:

- **Relationship type**: Select a type of relationship.
  - **Object relationship**: For one-to-one relationships.
  - **Array relationship**: For one-to-many relationships.
- **Relationship name**: Create a name for the relationship.
- **Reference schema**: Select a reference schema from your database.
- **Reference table**: Select a table from your database.
- **From**: Select a field returned in the action response.
- **To**: Select a column from the reference table to join the field to.

In this example, we're creating a relationship for the `createUser` action. We're creating a relationship called `user`,
from the `id` field returned in the action response, to the `id` column of the `users` table.

<Tabs groupId="user-preference" className="api-tabs">
<TabItem value="console" label="Console">

- Head to the `Actions -> [action-name] -> Relationships` tab.
- Click `Add a relationship`.

  <Thumbnail
    src="/img/schema/add-action-relationship.png"
    alt="Opening the action relationship section"
    width="600px"
  />

- In the section opened by the above step, fill out the following fields and hit `Save`.

  <Thumbnail src="/img/schema/define-action-relationship.png" alt="Defining the relationship" width="700px" />

</TabItem>
<TabItem value="cli" label="CLI">

You can add an action relationship by adding it to the respective custom type in the `actions.yaml` file inside the
`metadata` directory:

```yaml {4-11}
- custom_types
  - objects
    - name: UserOutput
      relationships:
      - remote_table:
          schema: public
          name: users
        name: user
        type: object
        field_mapping:
          id: id
```

Apply the Metadata by running:

```bash
hasura metadata apply
```

</TabItem>
<TabItem value="api" label="API">

You can create an action relationship when defining custom types via the
[set_custom_types](/api-reference/metadata-api/custom-types.mdx#metadata-set-custom-types) Metadata API:

```http {20-29}
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
  "type": "set_custom_types",
  "args": {
    "scalars": [],
    "enums": [],
    "input_objects": [],
    "objects": [
      {
        "name": "UserOutput",
        "fields": [
          {
            "name": "id",
            "type": "Int!"
          }
        ],
        "relationships": [
          {
            "name": "user",
            "type": "object",
            "remote_table": "users",
            "field_mapping": {
              "id": "id"
            }
          }
        ]
      }
    ]
  }
}
```

</TabItem>
</Tabs>

### Step 3: Explore with GraphiQL

In the `API` tab, test out your action relationship.

<GraphiQLIDE
  query={`mutation {
  createUser(name: "Hodor") {
    id
    user {
      name
      auth0_id
    }
  }
}`}
  response={`{
  "data": {
    "createUser": {
      "id": "7ffd68ba-535e-4c72-9051-17cd4e8ed594",
      "user": {
        "name": "Hodor",
        "auth0_id": "hodor|hodor"
      }
    }
  }
}`}
/>

If your table has an existing
[remote relationship](/schema/postgres/remote-relationships/remote-schema-relationships.mdx), you can also query the
fields from the Remote Schema.

<GraphiQLIDE
  query={`mutation {
  createUser(name: "Hodor") {
    id
    user {
      name
      auth0_id
      auth0_profile {
        email
        nickname
        last_login
      }          
    }
  }
}`}
  response={`{
  "data": {
    "createUser": {
      "id": "7ffd68ba-535e-4c72-9051-17cd4e8ed594",
      "user": {
        "name": "Hodor",
        "auth0_id": "hodor|hodor",
        "auth0_profile": {
          "email": "hodor@hodor.com",
          "nickname": "Hodor",
          "last_login": "2016-05-22T01:35:48.863Z"
        }
      }
    }
  }
}`}
/>

In the [Remote Schema relationships](/schema/postgres/remote-relationships/remote-schema-relationships.mdx) section, we
joined our `users` table with a remote [Auth0](https://auth0.com/) schema. Here, we're able to get the Auth0 profile
data of the user returned from our action.
